docs: expand RequestOptions.vf() with vf_ wire-format rules - #1840
Open
jacalata wants to merge 5 commits into
Open
docs: expand RequestOptions.vf() with vf_ wire-format rules#1840jacalata wants to merge 5 commits into
jacalata wants to merge 5 commits into
Conversation
The vf_ view filter has several server-side quirks that aren't obvious from the current one-line docstring. Document what values actually mean on the wire: exact match by default, comma as OR-list, backslash-escape for literal comma, empty-value override behavior, no wildcards, no operators, boolean 'true'/'false' only. This surfaces the behavior verified end-to-end against Tableau Cloud while working through --filter parsing issues in tabcmd, so callers who build vf_ requests through TSC know what the server will accept without having to reverse-engineer it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The `filter=` list-endpoint syntax is unrelated to view-filter export requests (it's for querying lists of workbooks/users/etc). Steering readers there was scope creep. Just say ranges/operators aren't supported and point at workbook-side design. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Empirically verified: '\' in a vf_ value is the escape character. To
match a literal backslash you must double it ('\\'). Consolidate the
comma-escape and backslash rules into a single "backslash escapes"
bullet, since it's one mechanism.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Dropped the abstract "\c means literal c" phrasing (weird to read with a random letter) and led with the two concrete cases -- escape a comma, escape a backslash -- and noted why each escape matters (comma would otherwise start an OR-list; backslash otherwise consumed as escape). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Empirically tested 20+ candidate metacharacters (/ % + : ; { } [ ] ( )
? # * @ = & " ' < >) against a live server; every one passes through
untouched when URL-encoded. Only ',' and '\' are vf_ metacharacters
that need escaping in the wire value. Explicitly call that out so
readers don't assume everything URL-special needs a client-side
workaround.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The
vf_REST view filter has several server-side quirks that aren't obvious from the current one-linevf()docstring. This expands it to document what values actually mean on the wire: exact-match by default,,as OR-list,\,for a literal comma, the empty-value override behavior, no wildcards, no operators, boolean'true'/'false'only.Callers who build
vf_requests through TSC no longer have to reverse-engineer server behavior to figure out why their filter returned zero rows.Why now
Working through
--filterparsing bugs in tabcmd, I verified the wire-format behavior end-to-end against Tableau Cloud. Recording those findings in the library the tabcmd (and other callers) build on top of, so the next person doesn't have to redo the experiment.Notable server-side behaviors documented:
Rock\, Paper\, Scissors— backslash-escape works for a literal comma.%2Cdoes NOT.vf_Region=(empty value) — overrides any workbook-embedded filter on that column. Undocumented but stable and useful.*— NOT a wildcard onvf_. It's a wildcard on thefilter=list-endpoint syntax, which is a different query parameter.Test plan
help(PDFRequestOptions.vf)renders the expanded docstring cleanly🤖 Generated with Claude Code